Add MCP server documentation #20634

dinasaur404 · 2025-03-07T18:42:50Z

Summary

New page in Agents documentation that explains how to build an MCP server on Workers. It includes setup instructions for creating an MCP server on Workers, example code, configuration instructions for MCP clients, and what's coming soon!

Screenshots (optional)

Documentation checklist

[X ] The documentation style guide has been adhered to.
If a larger change - such as adding a new page- an issue has been opened in relation to any incorrect or out of date information that this PR fixes.
Files which have changed name or location have been allocated redirects.

src/content/docs/agents/examples/build-mcp-server.mdx

github-actions · 2025-03-07T18:53:48Z

Preview URL: https://c58405c8.preview.developers.cloudflare.com
Preview Branch URL: https://add-mcp-docs.preview.developers.cloudflare.com

Files with changes (up to 15)

Original Link	Updated Link
https://developers.cloudflare.com/agents/examples/build-mcp-server/	https://add-mcp-docs.preview.developers.cloudflare.com/agents/examples/build-mcp-server/

github-actions · 2025-03-07T18:58:39Z

Howdy and thanks for contributing to our repo. We review internal PRs within 1 week. If it's something urgent or has been sitting without a comment, start a thread in the Developer Docs space internally.

irvinebroque · 2025-03-07T19:06:55Z

src/content/docs/agents/examples/build-mcp-server.mdx

+import { MetaInfo, Render, Type, TypeScriptExample, WranglerConfig } from "~/components";
+import { Aside } from '@astrojs/starlight/components';
+
+[Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) is an open standard that allows AI assistants & LLMs to interact with services directly. If you want users to access your service or product straight from their AI assistant, you can enable this by spinning up an MCP server for your application. 


their AI assistant

Can we name some to orient people to what we mean?

yeah i think some examples would be useful.

irvinebroque · 2025-03-07T19:07:51Z

src/content/docs/agents/examples/build-mcp-server.mdx

+## Building an MCP Server on Cloudflare Workers
+
+Normally, setting up an MCP server requires writing boilerplate code to handle routing, define types, and standing up a server that implements the MCP protocol. But with [Cloudflare Workers](/workers/), all the heavy lifting is done for you, so all you need to do is define your service's functionality as TypeScript methods on your Worker
+Once deployed, your Worker becomes an MCP server that AI assistants (as long as they support MCP) can connect to and use to interact with your service.


support MCP

Think saying "MCP client" helps orient the reader?

irvinebroque · 2025-03-07T19:08:37Z

src/content/docs/agents/examples/build-mcp-server.mdx

+Once deployed, your Worker becomes an MCP server that AI assistants (as long as they support MCP) can connect to and use to interact with your service.
+
+<Aside type="caution">
+Remote MCP servers are not supported yet. The workers-mcp tooling creates a local proxy that forwards requests to your Worker, allowing the server to be used by an MCP client.


Is this necessary callout at least as of today given there aren't really remote MCP clients?

IMO worthwhile otherwise it's confusing what actually happens here

irvinebroque · 2025-03-07T19:12:16Z

src/content/docs/agents/examples/build-mcp-server.mdx

+- Shared-secret security using Wrangler Secrets
+- Installs a local proxy so you can access it from your MCP desktop clients (like Claude Desktop)
+
+### Set up the MCP Server


I think it would help to find a way to bring the code way up to the top as a kind of:

MCP =

On Workers, it's simple and TypeScript-native, it looks like this:

Explain the code you just saw (the jsdoc == the tool description (link to MCP spec), the boilerplate is handled (link to workers-mcp library so someone can read source code and understand)

Think faster we can show "here is code" and get someone saying "okay i get it, that is simple" — then after doing the step by step — then we don't bury the example

irvinebroque · 2025-03-07T19:13:28Z

src/content/docs/agents/examples/build-mcp-server.mdx

+/Users/username/path/to/my-new-worker/node_modules/.bin/workers-mcp run my-new-worker https://my-new-worker.username.workers.dev /Users/username/path/to/my-new-worker
+```
+
+#### Other MCP clients


Link to https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/tutorials#set-up-model-context-protocol-mcp ?

rita3ko · 2025-03-07T19:56:34Z

src/content/docs/agents/examples/build-mcp-server.mdx

+import { MetaInfo, Render, Type, TypeScriptExample, WranglerConfig } from "~/components";
+import { Aside } from '@astrojs/starlight/components';
+
+[Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) is an open standard that allows AI assistants & LLMs to interact with services directly. If you want users to access your service or product straight from their AI assistant, you can enable this by spinning up an MCP server for your application. 


substitute assitants with agents?

rita3ko · 2025-03-07T19:56:51Z

src/content/docs/agents/examples/build-mcp-server.mdx

+import { MetaInfo, Render, Type, TypeScriptExample, WranglerConfig } from "~/components";
+import { Aside } from '@astrojs/starlight/components';
+
+[Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) is an open standard that allows AI assistants & LLMs to interact with services directly. If you want users to access your service or product straight from their AI assistant, you can enable this by spinning up an MCP server for your application. 


yeah i think some examples would be useful.

rita3ko · 2025-03-07T19:57:14Z

src/content/docs/agents/examples/build-mcp-server.mdx

+
+## Building an MCP Server on Cloudflare Workers
+
+Normally, setting up an MCP server requires writing boilerplate code to handle routing, define types, and standing up a server that implements the MCP protocol. But with [Cloudflare Workers](/workers/), all the heavy lifting is done for you, so all you need to do is define your service's functionality as TypeScript methods on your Worker


I wouldn't start here.

I would start with "In this guide, we will show you how to XYZ"

rita3ko · 2025-03-07T19:58:22Z

src/content/docs/agents/examples/build-mcp-server.mdx

+   * @return {string} The greeting message.
+   */
+  sayHello(name: string) {
+    return `Hello from an MCP Worker, ${name}!`;


It would be really good to have some other step that allows you to call an API. even like the weather one that's in the MCP docs. but really showing what this allows you to do which is integrate with stuff

Think this is worthwhile

src/content/docs/agents/examples/build-mcp-server.mdx

irvinebroque · 2025-03-07T23:03:30Z

src/content/docs/agents/examples/build-mcp-server.mdx

+
+In this guide, you will learn how to build and deploy a Model Context Protocol (MCP) server on Cloudflare Workers.
+
+[Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) is an open standard that allows AI agents and assistants (like [Claude Desktop](https://claude.ai/download), [Cursor](https://www.cursor.com/), or [Anthropic's Claude](https://www.anthropic.com/claude)) to interact with services directly. If you want users to access your service through an AI agent, you can spin up an MCP server for your application.


this page could be helpful link: https://modelcontextprotocol.io/clients

irvinebroque · 2025-03-07T23:04:53Z

src/content/docs/agents/examples/build-mcp-server.mdx

+**How it works:**
+* **TypeScript methods as MCP tools:** Each public method in your class is exposed as an MCP tool that agents can call. In this example, getWeather is the tool that fetches data from an external weather API.
+* **Automatic tool documentation:** JSDoc comments define the tool description, parameters, and return values, so Claude knows exactly how to call your method and interpret the response.
+* **Build-in MCP compatibility:** The `ProxyToSelf` class handles all MCP protocol requirements


This isn't quite true and I think might misleads people — ProxyToSelf translates incoming requests into relevant JS RPC methods, but the actual handling of the MCP protocol, tool discovery, happens totally outside of the Worker, in the Node.js local proxy layer

irvinebroque · 2025-03-07T23:05:24Z

src/content/docs/agents/examples/build-mcp-server.mdx

+   * @return {string} The greeting message.
+   */
+  sayHello(name: string) {
+    return `Hello from an MCP Worker, ${name}!`;


Think this is worthwhile

rita3ko · 2025-03-10T15:37:42Z

src/content/docs/agents/examples/build-mcp-server.mdx

+
+
+### Deploy the MCP server
+Update your wrangler.toml with the appropriate configuration then deploy your Worker:


if there's anything you actually need in your wrangler.toml can you include it here and have wrangler.jsonc and wrangler.toml such as here:
https://developers.cloudflare.com/workers/static-assets/binding/

hyperlint-ai · 2025-03-10T15:41:55Z

PR Change Summary

Added a new documentation page for building an MCP server on Cloudflare Workers, providing comprehensive setup instructions and example code.

Introduced a tutorial on building an MCP server using Cloudflare Workers.
Included setup instructions and example code for creating an MCP server.
Outlined configuration steps for MCP clients and future enhancements.

Added Files

src/content/docs/agents/examples/build-mcp-server.mdx

How can I customize these reviews?

Check out the Hyperlint AI Reviewer docs for more information on how to customize the review.

If you just want to ignore it on this PR, you can add the hyperlint-ignore label to the PR. Future changes won't trigger a Hyperlint review.

What is Hyperlint?

Hyperlint is an AI agent that helps you write, edit, and maintain your documentation.

Learn more about the Hyperlint AI reviewer and the checks that we can run on your documentation.

Add MCP server documentation

Add MCP server documentation

1195e85

dinasaur404 requested review from a team, elithrar, harshil1712, irvinebroque, megaconfidence, rita3ko, thomasgauvin and threepointone as code owners March 7, 2025 18:42

hyperlint-ai bot reviewed Mar 7, 2025

View reviewed changes

github-actions bot assigned elithrar, harshil1712, irvinebroque, megaconfidence, rita3ko, thomasgauvin and threepointone Mar 7, 2025

github-actions bot added the product:agents Build and deploy AI-powered Agents on Cloudflare that can act autonomously. label Mar 7, 2025

github-actions bot added the size/m label Mar 7, 2025

irvinebroque reviewed Mar 7, 2025

View reviewed changes

rita3ko requested changes Mar 7, 2025

View reviewed changes

Update MCP server documentation based on PR feedback

7acd80d

hyperlint-ai bot reviewed Mar 7, 2025

View reviewed changes

src/content/docs/agents/examples/build-mcp-server.mdx Show resolved Hide resolved

Small fixes

b6df6ac

irvinebroque reviewed Mar 7, 2025

View reviewed changes

irvinebroque approved these changes Mar 7, 2025

View reviewed changes

Update ProxyToSelf class description for accuracy

9e33d5e

rita3ko reviewed Mar 10, 2025

View reviewed changes

restructure

af2e177

Add wrangler configuration section to MCP server docs

c58405c

rita3ko approved these changes Mar 10, 2025

View reviewed changes

dinasaur404 merged commit 4286f49 into production Mar 10, 2025
11 checks passed

dinasaur404 deleted the add-mcp-docs branch March 10, 2025 20:18

RebeccaTamachiro pushed a commit that referenced this pull request Apr 21, 2025

Add MCP server documentation (#20634)

7c312ec

Add MCP server documentation


		## Building an MCP Server on Cloudflare Workers

		Normally, setting up an MCP server requires writing boilerplate code to handle routing, define types, and standing up a server that implements the MCP protocol. But with [Cloudflare Workers](/workers/), all the heavy lifting is done for you, so all you need to do is define your service's functionality as TypeScript methods on your Worker


		In this guide, you will learn how to build and deploy a Model Context Protocol (MCP) server on Cloudflare Workers.

		[Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) is an open standard that allows AI agents and assistants (like [Claude Desktop](https://claude.ai/download), [Cursor](https://www.cursor.com/), or [Anthropic's Claude](https://www.anthropic.com/claude)) to interact with services directly. If you want users to access your service through an AI agent, you can spin up an MCP server for your application.



		### Deploy the MCP server
		Update your wrangler.toml with the appropriate configuration then deploy your Worker:

Add MCP server documentation #20634

Add MCP server documentation #20634

Uh oh!

Conversation

dinasaur404 commented Mar 7, 2025

Summary

Screenshots (optional)

Documentation checklist

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions bot commented Mar 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Mar 7, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

hyperlint-ai bot commented Mar 10, 2025

PR Change Summary

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

8 participants

github-actions bot commented Mar 7, 2025 •

edited

Loading